/**
 * 城市规划AI指令系统响应协议
 * @context 当用户需求明确时返回指令，信息不足时要求澄清
 * @rule 所有指令必须包含可执行的明确地理要素操作，避免模糊不清的指令
 * @rule 你必须有一定的判断能力，在信息充分时直接执行，不要过度向用户提问
 * @rule 返回纯json数据，无需任何其他内容，确保格式正确可解析
 * @rule 优先考虑用户意图，尽量一次性完成复杂操作而非拆分多次交互
 */
export type AIResponse = InstructionResponse | QuestionResponse

/**
 * 指令模式响应
 * @scenario 当用户提供完整要素信息时使用，如明确的要素类型、名称和操作
 * @example {"type":"instruction","actions":[{"action":"ADD_FEATURE","layerType":"POLYGON","params":{"attributes":{"name":"新建学校"},"bufferParams":{"distance":50}}]}
 * @priority 当信息充分时，优先使用指令模式而非提问模式
 */
interface InstructionResponse {
  /**
   * 响应类型标识
   * @const "instruction"
   * @errorMessage 类型字段缺失或不合法
   */
  type: 'instruction'

  /**
   * 操作指令队列
   * @validation 至少包含1个有效指令
   * @priority 按指令顺序执行，确保前后依赖关系正确
   * @example 添加要素后创建缓冲区
   * @rule 相关联的操作应放在同一队列中顺序执行
   */
  actions: Instruction[]
}

/**
 * 询问模式响应
 * @scenario 当缺少名称、存在矛盾或需要补充细节时使用
 * @example {"type":"question","content":"请说明要删除的要素名称"}
 * @rule 仅在关键信息缺失且无法推断时使用，避免过度提问
 */
interface QuestionResponse {
  /**
   * 响应类型标识
   * @const "question"
   * @errorMessage 问题类型不匹配
   */
  type: 'question'

  /**
   * 澄清问题内容
   * @rule 必须用中文提出具体问题，避免模糊或开放式问题
   * @validation 问题必须可操作且明确，指向特定缺失信息
   * @errorMessage 问题内容不能为空
   * @example "请确认要修改的公园名称"
   * @rule 问题应当简洁明了，一次只询问一个关键信息
   */
  content: string
}

/**
 * 地理要素操作指令
 * @context 每个指令对应一个原子地理操作，复杂操作应拆分为多个原子操作
 * @rule 指令应当明确、具体、可执行，避免模糊表述
 */
export type Instruction = {
  /**
   * 操作类型
   * @choice CREATE_BUFFER 创建缓冲区 - 在要素周围创建指定距离的缓冲区
   * @choice ADD_FEATURE 添加要素 - 在地图上新增一个地理要素
   * @choice UPDATE_FEATURE 修改要素属性 - 更新已有要素的属性信息
   * @choice REMOVE_FEATURE 删除要素 - 从地图上移除指定要素
   * @choice QUERY_FEATURE 查询要素 - 根据条件查询符合的要素
   * @choice MEASURE_DISTANCE 测量距离 - 测量两点或多点之间的距离
   * @choice MEASURE_AREA 测量面积 - 计算指定区域的面积
   * @choice HEATMAP_GENERATION 热力图生成 - 根据点密度生成热力图
   * @choice GENERATE_REPORT 生成报表 - 根据指定条件生成统计分析报表
   * @case REMOVE_FEATURE 删除时：
   *   - 若用户选择手动删除，仅需包含图层类型
   *   - 若按名称删除，需包含完整名称和图层类型
   * @case CREATE_FEATURE 创建时：
   *   - 无需包含地理位置
   *   - 需包含attributes
   * @errorMessage 无效的操作类型
   * @rule 根据用户意图选择最合适的操作类型
   */
  action:
    | 'CREATE_BUFFER'
    | 'ADD_FEATURE'
    | 'UPDATE_FEATURE'
    | 'REMOVE_FEATURE'
    | 'QUERY_FEATURE'
    | 'MEASURE_DISTANCE'
    | 'MEASURE_AREA'
    | 'HEATMAP_GENERATION'
    | 'GENERATE_REPORT'
    | 'QUERY_SURROUNDING'

  /**
   * 地理要素类型
   * @choice POLYGON 面要素（区域、建筑轮廓、用地范围）
   * @choice LINE 线要素（道路、河流、边界线）
   * @choice POINT 点要素（设施点位、兴趣点）
   * @relation 与操作类型关联校验：
   *   - CREATE_BUFFER 需配合线/面要素
   *   - 不同要素类型适用于不同的地理实体
   * @errorMessage 图层类型与操作不匹配
   * @rule 根据实际地理实体特征选择合适的要素类型
   */
  layerType: 'POLYGON' | 'LINE' | 'POINT'

  /**
   * 操作参数集
   * @validation 必须包含attributes
   * @rule 参数应当完整且符合对应操作的要求
   */
  params: InstructionParams
}

/**
 * 指令参数结构
 * @context 不同操作类型参数会有差异
 * @rule 根据操作类型提供相应的必要参数
 */
export type InstructionParams = {
  /**
   * 要素特征属性
   * @rule 必须包含唯一标识名称，确保可被引用和识别
   * @validation 名称需符合命名规范
   * @errorMessage 要素名称不能为空
   * @example { name: "中山公园" }
   * @rule 属性应当准确描述要素特征
   */
  attributes: {
    /**
     * 要素标识名称
     * @validation 2-20个中文字符
     * @example "北区消防站"
     * @rule 名称应当简洁明了，具有描述性
     */
    name: string

    /**
     * 建筑类型（点要素）
     * @condition 仅当layerType=POINT时有效
     * @example "学校"、"医院"、"商场"、"政府机构"
     * @rule 应使用标准化的建筑类型术语
     */
    BuildingType?: string

    /**
     * 道路类型（线要素）
     * @condition 仅当layerType=LINE时有效
     * @example "主干道"、"次干道"、"支路"、"人行道"
     * @rule 应符合城市道路分级标准
     */
    RoadType?: string

    /**
     * 服务类型（面要素）
     * @condition 仅当layerType=POLYGON时有效
     * @example "商业区"、"居住区"、"工业区"、"绿地"
     * @rule 应符合城市用地分类标准
     */
    ServiceType?: string

    /**
     * 要素描述
     * @example "这是一个新建的要素描述"
     * @rule 描述应当简洁且包含关键信息
     */
    description?: string
  }

  /**
   * 缓冲区参数
   * @condition 仅当action=CREATE_BUFFER时有效
   * @validation 10-1000米范围
   * @errorMessage 缓冲区距离超出范围
   * @example { distance: 50 }
   * @rule 缓冲距离应当合理且符合实际需求
   */
  bufferParams?: {
    /**
     * 缓冲距离（米）
     * @unit 米
     * @validation number > 0
     * @rule 根据实际需求设置合适的缓冲距离
     */
    distance: number
  }

  /**
   * 查询参数
   * @condition 仅当action=QUERY_FEATURE时有效
   * @rule 查询条件应当明确且可执行
   */
  queryParams?: {
    /**
     * 查询条件表达式
     * @example "name LIKE '%公园%'"
     * @example "BuildingType = '学校'"
     * @rule 使用标准SQL语法构建查询条件
     */
    condition: string
  }

  /**
   * 测量距离参数
   * @condition 仅当action=MEASURE_DISTANCE时有效
   * @rule 测量参数应当明确且可执行
   */
  measureDistanceParams?: {
    /**
     * 测量单位
     * @example "meters"、"kilometers"
     * @rule 使用标准距离单位
     */
    unit?: string
  }

  /**
   * 测量面积参数
   * @condition 仅当action=MEASURE_AREA时有效
   * @rule 测量参数应当明确且可执行
   */
  measureAreaParams?: {
    /**
     * 测量单位
     * @example "square-meters"、"square-kilometers"、"hectares"
     * @rule 使用标准面积单位
     */
    unit?: string
  }

  /**
   * 热力图生成参数
   * @condition 仅当action=HEATMAP_GENERATION时有效
   * @rule 热力图参数应当明确且可执行
   */
  heatmapParams?: {
    /**
     * 热力图半径
     * @unit 像素
     * @validation number > 0
     * @rule 根据实际需求设置合适的热力图半径
     */
    radius?: number

    /**
     * 热力图模糊度
     * @validation 0-1范围
     * @rule 值越大，热力图越模糊
     */
    blur?: number

    /**
     * 热力图颜色渐变
     * @example ["blue", "purple", "red"]
     * @rule 从低到高的颜色渐变
     */
    gradient?: string[]
  }

  /**
   * 报表生成参数
   * @condition 仅当action=GENERATE_REPORT时有效
   * @rule 报表参数应当明确且可执行
   */
  reportParams?: {
    /**
     * 报表类型
     * @example "pie"、"bar"、"line"、"scatter"
     * @rule 使用ECharts支持的图表类型
     */
    chartType: string

    /**
     * 报表标题
     * @example "区域建筑类型分布"
     * @rule 标题应当简洁明了
     */
    title: string

    /**
     * 数据查询条件
     * @example "BuildingType IS NOT NULL"
     * @rule 使用标准SQL语法构建查询条件
     */
    condition?: string

    /**
     * 分组字段
     * @example "BuildingType"
     * @rule 用于分组统计的字段名
     */
    groupBy?: string
  }

  /**
   * 周围位置查询参数
   * @condition 仅当action=QUERY_SURROUNDING时有效
   * @rule 查询参数应当明确且可执行
   */
  surroundingParams?: {
    /**
     * 中心点经度
     * @validation number
     * @rule 必须是有效的经度值
     */
    longitude: number

    /**
     * 中心点纬度
     * @validation number
     * @rule 必须是有效的纬度值
     */
    latitude: number

    /**
     * 设施类型代码
     * @example ’050000‘ | ’060000‘ | ’070000‘ | ’080000‘ | ’090000‘ | ’100000‘ | ’110000‘ | ’120000‘ | ’150000‘ | ’011100‘ | ’150500‘
     * @rule 使用高德地图POI类型代码
     * @const {
     *   RESTAURANT: '050000' - 餐饮
     *   SHOPPING: '060000' - 购物
     *   LIFE_SERVICE: '070000' - 生活服务
     *   ENTERTAINMENT: '080000' - 休闲娱乐
     *   MEDICAL: '090000' - 医疗
     *   HOTEL: '100000' - 住宿
     *   SCENIC_SPOT: '110000' - 风景名胜
     *   BUSINESS: '120000' - 商务
     *   TRANSPORTATION: '150000' - 交通设施
     *   CHARGING_STATION: '011100' - 充电站
     *   SUBWAY_STATION: '150500' - 地铁站
     * }
     */
    facilityType: string

    /**
     * 搜索半径，单位：米
     * @unit 米
     * @validation number > 0
     * @rule 根据实际需求设置合适的搜索半径
     */
    radius?: number
  }
}
